Skip to content

fmridisplay overhaul: stateful controller, unified colour pipeline, visualization walkthrough#87

Merged
torwager merged 6 commits into
masterfrom
fmridisplay-controller-overhaul
Jul 6, 2026
Merged

fmridisplay overhaul: stateful controller, unified colour pipeline, visualization walkthrough#87
torwager merged 6 commits into
masterfrom
fmridisplay-controller-overhaul

Conversation

@torwager

@torwager torwager commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Summary

Overhauls the fmridisplay display stack and adds a full multi-page visualization walkthrough. Two themes:

1. Display engine + colour pipeline

  • Stateful controller & multiview (@fmridisplay/controller.m, multiview.m): layers remember their source data and options, so montages and surfaces re-threshold/recolour/re-render live from one handle object. Every GUI control has a one-line command-line twin.
  • Unified colour pipeline (render_blobs.m, canlab_colormap.m, canlab_default_cmaprange.m): all montage modes (split / single / solid / continuous / indexed) build a single central_cm and colour through central_map_slice; the buggy indexmap sub2ind path and legacy continuous map_function path are removed. Result: max|dRGB| = 0 across montage modes, and surface indexmap vertex colours equal cmap(region_index) exactly.
  • Surfaces (render_layer_surfaces.m, render_on_surface.m): all modes incl. indexed/atlas route through the truecolor path with 'interp','nearest' for indexed; controller/surface legend handling for indexed atlases fixed.
  • Supporting: addblobs/removeblobs/surface/montage method updates, canlab_results_fmridisplay options, uifigure helpers (canlab_is_uifigure, canlab_hide_axes_toolbar), and expanded canlab_test_fmridisplay_handle coverage.

2. Visualization walkthrough (docs/visualization_walkthrough/)

A hands-on, six-page guide pairing runnable code with the figure it produces, covering montages, 3-D surfaces, the interactive controller, colormaps, and atlases:

  • index.md, 01_getting_started … 06_atlases_and_regions.
  • SPM-free canlab_orthviews + a pointer to the canlab_niivue web viewer; OO-API intro; custom montages via fmridisplay.montage; full catalogs of surfaces, composites, and montage-sets; atlas object help and the Neuroimaging_Pattern_Masks dependency.
  • Master script _gen/visualization_walkthrough.m — one section per page (1.1 … 6.5) — regenerates every figure; per-page gen_0*.m generators kept for single-page regen. Verified: runs end-to-end clean in MATLAB R2026a.

Also removes stray Dropbox conflict temp files under Unit_tests/walkthroughs/private/ and minor typo/codespell fixes.

Test plan

  • canlab_test_fmridisplay_handle (extended) passes.
  • _gen/visualization_walkthrough.m runs end-to-end in R2026a, regenerating all figures with no errors.
  • Colour-equivalence checks: max|dRGB| = 0 across split/single/solid/continuous montage modes; surface indexmap vertex colours match cmap(region_index) (d=0).

🤖 Generated with Claude Code

torwager and others added 6 commits July 1, 2026 14:35
@torwager @claude
fmridisplay: stateful controller, multiview, uniform colour scaling, …
7f0c46a 
…fixes

Interactive controller
- Auto-launch on construction (gated off in -batch / 'nocontroller'); restores
  the current figure so it never hijacks montage/surface rendering; opens
  top-right to avoid overlap.
- Threshold slider fixes: normalised [0 1] scale for raw |x| (uislider is
  unreliable on tiny ranges), double-cast (data-derived thresholds are single),
  numeric entry field, out-of-range shows an empty map.
- Split-colormap legend: 4 numeric labels + gap, live-updating with cmaprange.
- Colour bar renders via uiimage (fills the cell); larger legend font.
- Echoed code + title use the caller's real workspace variable name.

Layouts / entry points
- New fmridisplay.multiview method exposing all canlab_results_fmridisplay
  compositions (compact/compact2/full/multirow/hcp/freesurfer/subcortex/...).
- canlab_results_fmridisplay reuses a passed-in object: composes onto it if it
  has no montages, else just adds blobs (long-standing reuse preserved).
- fmridisplay.montage default routes through multiview('compact') (sag+axial
  combo, matching fmri_data.montage) and echoes the equivalent call.
- montage pulls existing blob layers onto a newly added montage; surface
  multi-keyword path (foursurfaces_hcp, ...) routes through addbrain.

Uniform colour scaling
- Shared canlab_default_cmaprange: robust per-arm percentile default used by
  montages, render_on_surface, and the surface path (no more min/max vs
  percentile divergence).

Consistency / robustness fixes
- Shared canlab_is_uifigure: never draw slices/surfaces into the controller
  uifigure (open a fresh figure instead) across all entry points.
- removeblobs clears surface-only layers (no montage blobhandles).
- Multi-image objects handled without errors: montage() lays out a per-image
  (multirow) display (fixed existing_axes expansion for a single placeholder
  axis with many slices); addblobs() uses the first image only.
- Hide the per-axes "..." interaction toolbar on montage slices and rendered
  surfaces (canlab_hide_axes_toolbar).

Tests
- Add regression tests: existing_axes expansion, multi-image montage/addblobs,
  multiview compose+pull-in; update the split-legend label test. 47/47 pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZJacdhhByLGXqGHH9YQeo
@torwager @claude
fmridisplay: route all montage colour modes through central canlab_co…
700f5a5 
…lormap

Unify montage value->colour with the surface path by building the central
canlab_colormap for EVERY mode, not just split/single. Previously solid,
continuous ('colormap' LUT) and indexed ('indexmap'/atlas) blobs used legacy
inline render_blobs paths that bypassed canlab_colormap; the indexmap path was
also buggy (broken sub2ind assignment). Now:

- render_blobs builds central_cm for split, single, solid, continuous and
  indexed, and colours every slice via central_map_slice (one code path).
- canlab_colormap.map is NaN/Inf-robust for indexed and continuous, matching
  the legacy guards, since blob slices contain out-of-blob NaN voxels.

Montage and surface of the same data now produce identical value->colour
mappings across all colour modes (verified max|dRGB|=0), and the buggy indexmap
rendering is removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@torwager @claude
fmridisplay: unify indexed/atlas colours in controller + surface
4d3ad93 
Route indexed (indexmap/atlas) layers through the central canlab_colormap
everywhere, so montage, surface, and the controller legend all agree:

- canlab_colormap.from_render_args now builds an 'indexed' colormap for
  indexmap layers (was falling through to the default mango split).
- controller: indexed layers show an 'indexed (atlas)' label, the region's
  solid colour as the swatch/stripe (not the whole palette), and blank the
  meaningless numeric range labels.
- render_layer_surfaces: index/atlas surfaces render through the same
  true-colour central-colormap path as every other mode (nearest-neighbour
  sampling to preserve integer indices), replacing the render_on_surface
  legacy indexmap branch.

Verified: surface vertex colours equal cmap(region_index) exactly (d=0) and
match the montage; split/single/solid/continuous unaffected.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@torwager @claude
Add visualization walkthrough docs (multi-page guide + figures)
91e9d11 
Multi-page markdown walkthrough of CanlabCore visualization methods:
getting started, montages, surfaces, colormaps, the fmridisplay
controller GUI with command-line equivalents, and atlases/regions.
Includes per-section figure generators (_gen/) and embedded figures.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@torwager @claude
Walkthrough revisions: canlab_orthviews/niivue, custom montage, catal…
baa7176 
…ogs, master script

Applies the 8 approved revisions to the visualization walkthrough (docs only):
- §1: OO-API intro (methods return manipulable fmridisplay objects); add
  canlab_orthviews (SPM-free) + pointer to the canlab_niivue web viewer.
- §2.6: custom montage via fmridisplay.montage (orientation/slice_range/spacing).
- §3.4/§3.6: addbrain help pointers + full surface & composite catalog.
- §5.4: montage-set and surface-layout catalog.
- §6: atlas object help, atlas-type table, Neuroimaging_Pattern_Masks dependency.
- Clean surface figures without colorbar legends; new 01_canlab_orthviews.png
  and 02_custom_montage.png.
- Add master script _gen/visualization_walkthrough.m (one section per page,
  regenerates all figures; ran clean in R2026a); referenced from §1 and index.
- Remove temporary _gen/gen_revise.m; fix R2026a func(){:} syntax in docs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@torwager @claude
docs: link visualization walkthrough from Object_methods; organize RE…
86bc270 
…ADME doc sections

- Object_methods.md "Visualizing images and results": add a callout linking the
  new visualization_walkthrough/index.md as the hands-on starting point.
- README.md: reorganize the documentation list into "In this repository" vs
  "Online", adding the visualization walkthrough, workflows, and markdown
  tutorials sections alongside the existing Object methods reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@torwager torwager merged commit 495f687 into master Jul 6, 2026
2 checks passed
@torwager torwager deleted the fmridisplay-controller-overhaul branch July 6, 2026 05:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@torwager